home *** CD-ROM | disk | FTP | other *** search
/ Games of Daze / Infomagic - Games of Daze (Summer 1995) (Disc 1 of 2).iso / x2ftp / msdos / libs / mikdll / readme.doc < prev   
Encoding:
Text File  |  1995-03-25  |  5.6 KB  |  212 lines
  1. MikDLL by MikMak / HaRDCoDE '95
  2. ===============================
  3.  
  4. MikDLL is a set of routines which enable you to create & use your own
  5. dynamically loadable libraries for DOS, without having to use any assembly.
  6.  
  7. Now I can hear you thinking 'do I need this shit?', well most of you
  8. probably don't need it. But suppose you're writing a modplayer (hehe) and
  9. you have to support lots of different soundcards.. are you just going to
  10. statically link all those different drivers to your .exe and create one HUGE
  11. program which eats up a lot of memory?? NO! Use MikDLL to create separate
  12. MDLL .EXE files for each driver; when your modplayer starts, simply load and
  13. link the driver you need at that time.
  14.  
  15.  
  16. Advantages:
  17.  
  18.   - Smaller main .EXE
  19.  
  20.   - Uses less diskspace (the unused drivers can be deleted)
  21.  
  22.   - It's easier to add new functionality/support to your program.. you
  23.     only have to make a new MDLL and there's no need to rebuild the main
  24.     program.
  25.  
  26.   - You'll learn how to program in a more object-oriented fashion.
  27.  
  28.   - It's elegant (you eediot!).
  29.  
  30.  
  31. Before I go on I have to give some credit to Otto Chrons who invented (?)
  32. this kind of DLL (he uses it for DMP) (tho he didn't tell me about that dos
  33. function to load an executable ;)
  34.  
  35.  
  36. How does it work?
  37. =================
  38.  
  39. When you load a MDLL using the function MDLL_Bind() it does the following:
  40.  
  41.   - It reserves enough memory for the MDLL
  42.  
  43.   - It uses dos function 0x4b03 (EXEC-load overlay) to actually load &
  44.     relocate the .exe into the reserved memory.
  45.  
  46.   - It searches the overlay memory for a certain structure (TAG) by which
  47.     it can access the MDLL entry function.
  48.  
  49.   - It executes the entry function so the MDLL can import or export
  50.     certain functions or data.
  51.  
  52. Next, the main program can import routines/data that was previously
  53. exported by the MDLL entry function.
  54.  
  55.  
  56. Limitations
  57. ===========
  58.  
  59. - You can't use a library function of a MDLL if it needs some kind of
  60. initialisation in the startup-code of an .EXE, like printf(), malloc(),
  61. getenv().. if you have to use them anyway, use the parents functions by
  62. importing them into your MDLL.
  63.  
  64. - You'd better use the same memory model in both MDLL and parent programs,
  65. or else the parameter passing will fail.
  66.  
  67. - Borlands Tiny, Small, Medium and Compact libraries assume DS=SS which
  68. isn't the case with MDLLs.. this will affect some library functions like
  69. sprintf. My advice: use Large model only.
  70.  
  71. - Both the parent & MDLL programs have their own data segment. When calling
  72. a MDLL function from the parent and vice versa you have to make sure that
  73. each function uses the correct data segment by putting '_loadds' or 'huge'
  74. in front of every exported function.
  75.  
  76. - Do NOT pklite or lzexe the MDLL executable. The unpacking code won't be
  77. executed so the MDLL loader might execute garbage, resulting in a crash.
  78.  
  79.  
  80. Examples
  81. ========
  82.  
  83. I've included an example on how to use the MDLL functions. There's a program
  84. called PARENT.EXE that'll dynamically load CHILD.EXE and use one of it's
  85. functions and CHILD.EXE uses one of the parent functions. Neat huh?
  86.  
  87.  
  88. Future
  89. ======
  90.  
  91. All MDLL executables have 4k of startup code which isn't needed.. by using
  92. your own startup code (replacing c0x.asm) you could reduce the size of the 
  93. MDLLs. You could also use this to place the entry TAG on a fixed location
  94. within the .exe so the MDLL loader doesn't have to search for it.
  95.  
  96.  
  97. Feedback
  98. ========
  99.  
  100. Send your questions, comments, bugreports or money to:
  101.  
  102. Email:  mikmak@stack.urc.tue.nl
  103.  
  104. Smail:  Jean-Paul Mikkers
  105.     Godartstr. 16
  106.     5932 AX Tegelen
  107.     the Netherlands
  108.  
  109.  
  110. Disclaimer
  111. ==========
  112.  
  113. This is public domain. Use at your own risk. Don't try to understand it.
  114.  
  115.  
  116. ----------------------------------------------------------------------------
  117.  
  118.  
  119.  
  120. void huge MDLL_Export(char *name,void *obj)
  121. ===========================================
  122.  
  123. Adds an object (function or a datablock) to the exports-pool so a MDLL can
  124. use that object in the future.
  125.  
  126.    Input:
  127.  
  128.     char *name : The ASCIIZ name of the object to be exported, by
  129.              which it will be registered in the exports-pool.
  130.  
  131.     void *obj  : The address of the object to be exported.
  132.  
  133.  
  134.     Returns:     -
  135.  
  136.  
  137.  
  138. void * huge MDLL_Import(char *name)
  139. ===================================
  140.  
  141. Finds the address of an object by reference of it's name. This routine is
  142. used by a DLL to access external functions/data.
  143.  
  144.     Input:
  145.  
  146.     char *name : The ASCIIZ name of the object to be imported.
  147.  
  148.  
  149.     Returns:
  150.  
  151.     The address of the object.
  152.  
  153. Note:
  154. When the object can't be found, this function will report the failure and
  155. exit the program.
  156.  
  157.  
  158.  
  159. int MDLL_Bind(MDLL *mp,char *name)
  160. ==================================
  161.  
  162.     Input:
  163.  
  164.     MDLL *mp   : pointer to an uninitialised MDLL structure which is 
  165.              used to store information of the MDLL.
  166.  
  167.     char *name : The name of the executable which has to be loaded
  168.              as an MDLL.
  169.  
  170.  
  171.     Returns:
  172.  
  173.     1 - No problem
  174.     0 - An error occured. use MDLL_Error() to find out what went wrong.
  175.  
  176.  
  177.  
  178. void MDLL_Unbind(MDLL *mp)
  179. ==========================
  180.  
  181. Frees the memory taken up by the MDLL and removes the exports from this MDLL
  182. from the exports-pool. !! Only use this function when MDLL_Bind was
  183. succesful !!
  184.  
  185.     Input:
  186.  
  187.     MDLL *mp : pointer to a MDLL structure (which was filled by
  188.            MDLL_Bind() )
  189.  
  190.     Returns:
  191.     
  192.     -
  193.  
  194.  
  195.  
  196. char *MDLL_Error(void)
  197. ======================
  198.  
  199. Returns an error-string which describes what went wrong loading a MDLL.
  200.  
  201.  
  202.     Input:
  203.  
  204.     -
  205.  
  206.     Output:
  207.  
  208.     the error description string
  209.  
  210.  
  211. ----------------------------------------------------------------------------
  212.